<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>API changes in Jena2</title>
<link href="styles/doc.css" rel="stylesheet" type="text/css">
</head>
<body>

<h1>introduction</h1>

This document summarises API changes in Jena2. Many of these changes are
additions, but there are some removals and incompatible changes.

<h1>Statement.set</h1>

The <i>Statement.set(X)</i> methods have been removed. In its place we have
the <i>Statement.changeObject(X)</i> methods. These methods update the model
in the same way, but they do <i>not</i> alter the Statement object - they
construct a new one and return it. This avoids certain technical difficulties
which arose from having mutable Statement objects.

<h1>the DAML interface</h1>

[To Be Done]

<h1>namespace prefixes</h1>

Models now have associated prefix-namespace mappings. The readers notice any
mappings in their input streams and add them to the model; the writers use
those namespace prefixes (if appropriate) in their output.

<p>
The user may read and write the prefix mappings, either one at a time or from
other <i>PrefixMapping</i>s and <i>Map</i>s. Operations are provided that
convert a URI to a QName (if possible) using the prefixes, and back the other
way.

<p><i>Model</i> extends the interface <i>PrefixMapping</i> for the namespace
methods; see the Javadoc for more details.

<p>There is a "standard" set of prefix mappings (covering, in particular,
rdf:, rdfs:, owl:, and daml:) in <i>PrefixMapping.Standard</i>.

<h1>bulk update</h1>

The model API has been extended with "bulk update" operations which
implementations of <i>Model</i> are expected to implement efficiently.

<ul>
    <li><i>add(Statement [])</i> adds all of the statements in the array to
    the model.

    <li><i>add(List)</i> adds all of the statements in the List to
    the model. It is an error if any of the elements are not
    <i>Statement</i>s.

    <li><i>remove(Statement [])</i> removes all of the statements in the
    array to the model.

    <li><i>remove(List)</i> removes all of the statements in the List to
    the model. It is an error if any of the elements are not
    <i>Statement</i>s.
</ul>

In addition, the existing <i>add(Model)</i> and <i>remove(Model)</i>
implementations have been modified to use the bulk update interface if
possible.

<h1>Exceptions</h1>

The root of the Jena exception hierarchy is now
<i>com.hp.hpl.jena.shared.JenaException</i>. <i>RDFException</i> still exists
but will be deprecated and the error-code functionality it provided has been
replaced by specific sub-classes of JenaException (so that they may be
specifically caught). Look in .shared for most of these subclasses.

<h1>inference support</h1>

[To Be Done]

<h1>listStatements(S, P, O)</h1>

An extra version of <i>listStatements</i> taking separate subject, predicate,
and object arguments is available. This avoids the user having to create a
<i>SimpleSelector</i> in many cases.

<h1>rdfNode.inModel(Model)</h1>

The <i>RDFNode</i> method <i>inModel(Model m)</i> constructs a version of the
<i>RDFNode</i> that is "in" the model <i>m</i> and returns that node.
If the <i>RDFNode</i> is a <i>Literal</i>, or already in <i>m</i>, then
it is returned unchanged.

<h1>Model::isEmpty()</h1>

Model's method <i>isEmpty</i> returns true if and only if the model is
empty, that is, if <i>size()</i> would return 0 or <i>listStatements()</i>
would return an empty iterator. Implementations of <i>Model</i> may
be significantly more efficient than either of these alternatives.

<h1>rdfNode.as(Class)</h1>

This method converts an <i>RDFNode</i> of one kind to another, if possible,
throwing an exception if it cannot. The <i>Class</i> argument is the class
of the interface that is being converted to.

The boolean method <i>canAs(Class)</i> returns true iff it's possible
to convert this resource to one of the given class.

<h1>aModel.executeTransactionIn(Command cmd)</h1>

This new method executes the Command [defined in
<strong>com.hp.hpl.jena.shared</strong>] within a new transaction. If the
command fails (ie, throws an exception), then the transaction is aborted;
otherwise it is committed. This operation is built on the transaction
primitives.

<h1>Resource.visitWith(RDFVisitor rv)</h1>

An RDFVisitor defines visitURI, visitBlank, and visitLiteral; the appropriate
one of these is called when visitWith is run. Allows type-dependant decisions
to be made about what to do to a Node without needing to dance around
instanceof, and the "essential information" about the node (URI, AnonId, or
Literal) to be obtained without casting.

<h1>aModel.containsResource(RDFNode r)</h1>

This boolean method returns true iff <i>r</i> appears somewhere in
<i>aModel</i> as the subject, predicate, or object of some statement.

<h1>createResource(AnonId)</h1>

An extra <i>createResource</i> method is availble that creates a blank
(anonymous) node with a specified <i>AnonId</i>.

<h1>Resource.removeAll( Property p )</h1>

This method removes from the resource all the statements using the predicate
<code>p</code>, and returns the resource.

<h1>ModelFactory</h1>

<i>ModelMem</i> is obsolete. For a few-frills memory-based model, use
<i>ModelFactory.createDefaultModel()</i> instead.

[To Be Continued]

<h1>reification</h1>

Statements are no longer Resources. Instead Statements can be converted into
Resources using the asResource() method. These new Resources are
<i>ReifiedStatement</i> objects. See <a href="reify-api.html">the API
proposal</a> document for the moment.

<h1>typed literals</h1>

[To Be Done]

<h1>query<h1>

[To Be Done - Chris is going to add a API for some of the fast-track query]

<h1>iterators</h1>

Iterators now implement <i>java.util.iterator</i>, which means the
<i>.next()</i> method returns an Object rather than a typed object.  You need
to either cast the return from the <i>.next()</i> method to the appropriate
type or use the .next<i>Type</i>() (where <i>Type</i> is <i>Resource</i>,
<i>Literal</i>, <i>Ns</i>, <i>RDFNode</i> or <i>Statement</i> depending on the
iterator) to avoid casting.

<h1>event handling</h1>

It is now possible to attach listeners to a Model. Each listener must implement
<i>ModelChangedListener</i> and is informed of all statement-oriented updates
to the model, <i>ie</i> add/remove of <i>Statement</i>, <i>Statement[]</i>,
<i>List</i> (of <i>Statement</i>), <i>StmtIterator</i>, or <i>Model</i>.

<p>Convenience classes implementing <i>ModelChangedListener</i> are in 
<b>.model</b>'s sibling package <b>.listeners</b>, including listeners
that simply record that a change has occurred and listeners that convert
all updates into single-statement adds and removes.

 
<h1>I/O</h1>

See <a href=IO/iohowto.html#rush">the IO mini HowTo</a>.

</body>
</html>
